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Getting Started 


The HP 48 Programmer’s ToolKit is a collection of software tools 
designed with the programmer in mind. These tools improve 
program performance by combining some common, slow 
operations into faster internal system languages and provide 
additional capability in object manipulation not directly available 
in the HP 48 command set. 


There are seven main chapters and several reference tables in 
this manual: 


e Character Set Catalog describes an interactive character 
set catalog. 


e Menu Label Builder describes an interactive program for 
building graphics objects for use in custom menus. 


e Flag Catalog describes the interactive Flag Catalog. 


e Data Browser and Title Browser describe two powerful 
screen - oriented user interface utilities that may be used to 
enhance the appearance of an application. 


e Tool Library describes the new commands provided in the 
Tool Library, including the meta— object concepts used by 
some of the new commands. 


e Command Reference describes the full syntax for each new 
command in the Tool Library with examples. 


e Additional chapters provide reference tables for object 
types, the character set, and flags. 


Additional Information 

Part 5 of The HP 48 Owner's Manual discusses data transfer. The 
documentation that comes with the Serial Interface Kit for an 
IBM-compatible personal computer (HP 82208A) or an Apple 
Macintosh computer (HP 82209A) may also be helpful. 
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The HP 48 Handbook by the same author contains complete 
stack diagrams for all the HP 48 commands, further discussions 
of graphics, menus, data transfer topics, and includes other 
helpful information and reference tables. 


Installing the ToolKit 

The HP 48 Programmer's ToolKit consists of two system 
programs and four library objects that extend the built-in 
command set. All objects must be downloaded in binary mode. 


System Program Character Set Catalog 
System Program Menu Label Builder 


Library Flag Catalog 
Library Tool Library 
Library Title Browser 
Library Data Browser 





Installing System Programs 

The system programs CSCAT and LBLD are implemented in 
system languages and must be downloaded to the HP 48 in 
binary mode. They may be stored in any variable and evaluated 
like any other program. 


Note: When CSCAT and LBLD are on the stack, the copyright 
message appears. The programs may not be edited. If you press 
or (¥} while they are in level one, the HP 48 will take a very 
long time to display the programs in the command line. Pressing 
thereafter will only result in a Syntax Error. To abort the 
long display delay, just press [ATTN). 
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Installing Library Objects 

Libraries are referenced by a /ibrary# or a library identifier 
( : port#: library# ), depending on the command. The title of a 
library may be displayed by pressing [4] in the 
LIBRARY menu. 


Library objects only extend the command set when they are 
stored in a port (0, 1, or 2) and attached to a directory in user 
memory. To install a ToolKit library, perform the following: 


e Download the library to the HP 48 in binary mode. 
e Recall the library to the stack. 
e Purge the variable that the library was stored in. 


e Store the library object in a port, such as port 0. For instance, 
when the library object is in level one of the stack, execute 
0 STO. 


e Turn the calculator off, then on again. The calculator will 
perform a _ system halt, which updates the system 
configuration to recognize the new library. All ToolKit libraries 
automatically attach themselves to the HOME directory. 


Removing the ToolKit 

To remove the Alpha Catalog and the Label Builder, just purge the 
variable in which they are stored. To remove ToolKit libraries, 
perform the following steps: 


e Ensure that the library object to be purged does not appear 


on the stack as Library nnn: ... Either store the 
library in a variable or execute NEWOB to create a unique 
copy. 


e The ToolKit libraries are attached to the HOME directory. 
Switch to the HOME directory, enter the port-tagged 
library number, such as_: 4: 775 and execute DETACH. 


e Enter the library number as above and execute PURGE. 
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Example Programs 

There are several example programs and program fragments in 
this book. Each complete program is named and printed with a 
size and checksum. 


All characters in the programs are case-sensitive. The names of 
commands are always uppercase. By convention, the names of 
global variables are uppercase and of local variables are 
lowercase. 


While the command line entry of a program may be free form, 
with the keystroke being valid between words, graphics 
objects must be entered exactly as shown, with no extra breaks in 
the command line when entering the data. 


If you type a program into the HP 48, use the BYTES command to 
make sure the program in the calculator matches the version in 
the book. For instance, the program « DROF SHAPF is 15 
bytes long and has the checksum #5197h. The sizes for named 
programs include the size of the program name. Named 
programs may be found on the disk. 


Note: The libraries used by example programs must be installed 
before an example program is either entered or downloaded into 
the HP 48. For instance, the LUNCH example on page 21 uses 
commands from the Data Browser and the Tool Library. 
Therefore the Data Browser and Tool Library must be installed 
before LUNCH is entered, otherwise the library commands (such 
as DBR or PRVOB) will be interpreted as names, and the example 
programs will not work properly. 
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Character Set Catalog 


The Character Set Catalog provides an interactive character set 
catalog (see Character Codes). To display the Character Set 
Catalog, execute the system program CSCAT: 


CHR HEX DEC OCT’ BIN 
01000001 


01000101 


01000116 

01000111 

01001000 
| +32_ 





The display above shows eight characters at a time. Each 
character is shown with its character code displayed in HEX, 
DECimal, OCTal, and BINary modes. The right side of the display 
shows the character in three additional forms: 


e The character in the large (5x9) font. 
e The character in the medium (5x7) font. 


e Translated using the current TRANSIO setting. The TIO 1 
label reflects the current TRANSIO setting. 


The display above assumes the current TRANSIO setting is 1. 
The display below shows the display with character codes 136- 
143 displayed and TRANSIO set to 3: 


DEC OCT BIN 
10001000 


216 16 
10001111 
+32 | -64_ 
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When the catalog is displayed, you can do the following 
e Press the arrow keys to move the pointer. The left shifted 
arrow keys move a screen (8 characters) at a time. The 
right shifted arrow keys move to character codes 0 or 255. 
|= menu keys to move the 





e Press the =16. or 
pointer backwards or forwards 16 characters. 
e Press the =32 _ +32. menu keys to move the 
pointer backwards or forwards 32 characters. For AZ, 
_ yields lowercase a—z 
-64 menu keys to move the 





e Press the ces E 
pointer backwards or forwards 64 characters. For A-Z, 
&4 yields control codes control -A—control-Z. 








e Press [ENTER] to return the character code to the stack as 
an alpha-tagged character code, suchas A:65 


1: A? 65 
[PHRTS] PROE | WP [MATE VECTR) EWE | 





By executing OBJ— on the result, the character and its 
code are available as separate objects. 


e Press to end the application 
Note: The current TRANSIO setting is stored in the reserved 
If this variable does not exist, CSCAT will create 


variable JOPAR. 
IOPAR in the HOME directory with default values. 
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Menu Label Builder 


The Label Builder has been designed to facilitate the creation of 
graphic menu key labels. It is used in conjunction with custom 
menu definitions supplied to the MENU or TMENU commands 
which may contain a 21x8 graphics object to define the menu 
label. 


Example: The following list contains a menu definition for four 
keys. Each key is labeled with a graphics object, and the first key 
has a different definition for the left and right shifts: 


ELEC (225 bytes, checksum #9447h) 


GROB 21 8 0000000000000 101008282006444C008282000 1010000000 
£ "160" "26en" "Seen" 5 


e 


GROB 21 8 OOODDDDD0AD0000A00000A000CFBF7000A00000A00000A000 
"CAPACITOR" 


GROB 21 8 000000004000004 1000045000F75 10004500004 100004000 
"GROUND" 


GROB 21 8 000000000000000750002 150E777500024500007 20000000 
il Voc u 


+ 
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The Label Builder. The variable LBLD contains the Label Builder. 
While primarily intended for creating graphic menu labels, the 
Label Builder is also useful for creating smaller graphics objects 
as well. 


To start the Label Builder, execute LBLD: 





The cursor appears in the upper-left corner of the grid, and the 
cursor coordinates are shown on the right side of the display. 
While the grid is displayed, you can do the following: 


e Press the arrow keys to move the cursor (wraparound is 
enabled). 


e Press [ENTER] to toggle the current state of a pixel. 


e Press $SBGR_ to return the subgrob defined by the 
upper-left corner and the cursor to the stack. 


e Press *#STK_ to return the menu key graphics object and 
its inverse to the stack. 


e Press [ATTN] to end the label builder. 


The second and fourth menu keys at the bottom of the display 
show how the menu key would appear in its final form: 
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The Label Builder returns a graphics object and its inverse to the 
stack: 


Graphic 21 x 8 


eee 





These graphics objects are ready to supply to a custom menu 
definition. The object returned to level 1 with the tag "Reg" 
represents the second menu key from the left in the builder; the 
level 2 object represents the fourth menu key. 


The Label Builder may also be used to prepare smaller graphics 
objects. For instance, to construct a small arrow, set the desired 
pixels and place the cursor on the lower- right pixel: 





then [ATTN] Ta is end the application. The graphics objects in levels 
one and two contain the arrow: 


Graphic 5 * 5 
Graphic 5 x 5 
ECT) EASE | 
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Flag Catalog 


The Flag Catalog provides a rapid view of all the system flags 
(-1 - -—64) and the user flags (1 - 64). To display the Flag 
Catalog, execute the command FCAT ( [4] FCLIE 
FCAT ). 


Viewing All Flag Settings 
When the Flag Catalog starts, the first display shows all the 
system flags: 


wo 
iC 
Wi 
pas 
o 
g 
ow 
tre) 


a 


E] 
i] 
1 
2 
a 
y 
5 
6 


mmc 
wunuuan 
aAananunn 
rue ee 
fuwueoomy 
aAnaanaaansS 
A 

AAAAMAAN 
Sec cccce 
Ununununununun 
nu cweo 
AAAAAAAN 
moe unui 
fuueKoumy 
AAAAAAAA 


1 
1 
1 
1 
1 
1 
1 





This display shows all the system flags or user flags at once. 
When all the flags are displayed, you can do the following: 


e Press the arrow keys to move around the display. The 
left— shifted arrow keys move to the boundaries, and the 
right — shifted arrow keys move to the first or last flags. 


e Pressthe SF = or =F menu keys to set or clear the 
indicated flag. 


e Press the S'S or USER menu keys to view either the 
system flags or user flags. 


e Press the GESC menu key to display the flag 
descriptions. 


e Press GUIT or to end the application. 
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Viewing Flag Descriptions 
The ESC. key displays the flag descriptions for either the 
system flags or user flags: 

System Flag Catalog 

x1c pit leatla SOLUTION 


OLIC CONSTANTS 
NUMERICAL RESULTS 
OT USED 


ec 
ac 
4CN 
53 
6 
7s 
BS 





wal 
nm 


Be Ee es ee 


When the flag descriptions are displayed, you can do the 
following: 


e Press the arrow keys to move the pointer. The left— shifted 
arrow keys move a screen at a time. The right-shifted 
arrow keys move to the ends of the list. 


e Pressthe SF or CF. menu keys to set or clear the 
indicated flag. 
e Press the S'S or USER menu keys to view either the 


system flags or user flags. 


e Press the ALL menu key to display the flag 
descriptions. 


e Press UIT or to end the application. 


Supplying User Flag Descriptions 

When the user flag descriptions are displayed, the current path is 
searched for the variable UFLAGS. If UFLAGS is a list containing 
strings, the first two characters of each string will be examined for 
a flag number, and the remainder of the string will be displayed 
as the flag description. 
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The following list supplies definitions for the flags used by the 
HP 82211A Solve Equation Library application card: 


UFLAGS (107.5 bytes, checksum #7BABh) 


t 
"6BUHIT TYPE = @=SI 1=ENGLISH" 
"61UNITS USED: G=ES 1=HO" 
"62PMT MODE = G=END 1=BEG" 

3 


User Flag Catalog 
C USER FLAG 
USER F 


5 
5 
5' 
6 
>6 
6 
6 
6 


fweKoumn 
AAAAAAM 





ee Se ee 


lf UFLAGS does not contain a list, or the list does not contain a 
valid string definition, UFLAGS will be ignored. 
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Data Browser 


The Data Browser is a utility which provides an efficient interface 
for examining and editing a series of objects. 


The Data Browser appears to the user as a list of optionally— 
labeled data with a movable pointer to indicate a choice: 
ADDRESS LIST 
JOE SMITH 
123 ANYSTREET 
ORVALLIS 





7338 
@3-555-1212 
a ee ee a 


In the display above, the pointer indicates the currently selected 
item, and the arrows in the upper-left corner of the display 
indicate that more data items reside above and below those 
shown in the display. Each line of the display contains a label 
(such as “Addr: ") and data (such as "123 ANYSTREET"). The 
menu keys have been defined by the input parameters. 


The input parameters to the Data Browser control the appearance 
of the data and the options available to the user. For instance, by 
omitting the title bar and specifying a small font, many data items 
can be shown in the display at once: 
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Input Parameters 
The input parameters to the Data Browser are four lists: 


Level 4: 


Level 3: 


Level 2: 


Level 1: 
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{ label list > 

This list contains the label objects. Long labels will be 
truncated to 25 characters. An empty list may be 
supplied if no labels are desired. 


{ data list + 
This list contains the data objects, and must contain at 
least one object. The data list and label list must be the 
same length. 


< menu label list + 

This list contains the objects which will be presented as 
menu labels. If the label object is an empty string, the 
menu label will be black and the menu key will generate 
an error beep when pressed. If the label object is the 
string "NULLKEY", the menu label will be white and the 
menu key will generate an error beep when pressed. A 
21x8 graphics object may be used for the key label 
(see The Menu Label Builder). An empty list is 
acceptable, but the display will still show black labels. 


{font first_item current_item edit_flag title 3 

The font is specified by a real number: 1 for the small 
font (8x5), or 2 for the medium font (5x7). The real 
number first_item specifies the index of the first data 
item displayed. The real number current_item 
specifies which data item will be pointed to by the 
pointer. If first_item specifies a row that would force 
the last data item to appear above the bottom of the 
display, the value is adjusted to place the last data item 
at the bottom of the display. If the pointer is off- 
screen relative to the first_item, the data is positioned 
to place the pointer in the display. If the real number 
edit_flag is non-zero, the user may edit the data 
items. If edit_flag<0, no type checking will be 
performed. The title is specified by a string. The title 
string may contain 21 characters. Longer strings will be 
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truncated to 20 characters with a trailing ellipsis (...) 
character. If an empty string is supplied, the top of the 
display will be used to present additional data and the 
arrows indicating data beyond the boundaries of the 
display will not appear. 


Output Parameters 
The results from the Data Browser are either three or four items, 
depending on the original state of the edit_flag: 


Level 4: 


Level 3: 


Level 2: 


Level 1: 


< data list > 

This list contains the data objects (which may have 
been edited). The data list will not be returned if 
edit_flag was zero. 


{ font first_item current_item edit_flag title 3 

This list is similar to the level 1 input list. The real 
number first_item is the index in the data list of the first 
data item displayed when the Data Browser terminated. 
The real number current_item is the index of the data 
item at the pointer when the Data Browser terminated. 
The font, edit_flag, and title are the same as the input 
parameter. 


current_item 
The real number current_item is the index of the data 
item at the pointer when the Data Browser terminated. 


terminator_key 
The terminator_key indicates how the user terminated 
the Data Browser: 


0: Zerois returned when the user presses [ATTN]. 
1: | One is returned when the user presses (ENTER). 


—n: If the result is a negative number, the absolute 
value indicates which menu key was pressed. 


Data Browser 15 


Active Keys 


While the Data Browser is running, the following keys are active: 
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(4) [¥) 


(P) (visit 


(4) (EDIT 


MEHU 


ENTER 


ATIN 


The arrow keys may be used to move the pointer. 
Press [4] and an arrow key to move the pointer 
one screen at a time. Press (>) and an arrow key 
to move to the ends of the catalog. 


If a data item cannot fit within the display (indicated 
by ...), the key displays as much of the item 
as will fit in the display, up to 154 characters. 
Pressing or will return to the original 
Data Browser display. If the data item fits entirely in 
the display, [@) will generate an error beep. 
See Viewing Large Data Items below. 


If the edit_flag is non-zero, pressing (4) 
presents a line editor for the current data item. The 
edit session can be aborted by pressing [ATTN], or 
accepted by pressing [ENTER]. The input supplied 
by the user is checked for proper syntax to confirm 
that a legitimate object results. See Editing Data 
Items below. 


Pressing [a] produces a prompt for a search string. 
The data list will be searched for a data item 
containing the search string starting at the next item 
and wrapping around if necessary. The search is 
case-sensitive. See Searching for Data below. 


Pressing a non-null menu key will terminate the 
Data Browser, indicating which menu key was 
pressed and the location of the pointer. 


Terminates the Data Browser, indicating the 
location of the pointer. 


Terminates the Data Browser. 
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Viewing Large Data Items. The Data Browser has a facility for 
viewing data items that are too large to fit within a line on the 
display. For example, consider the display below: 


ADDRESS LIST 

= JOHN DOE 

= 9876 WINCHESTE.. 
ORVALLIS 





7338 
@3-3555-1212 
Laoo | cee [ff Pui | 


The current data item will not fit in the display, as indicated by the 


ellipses (...) at the end of the line. Pressing [(P) produces a 
full-screen display showing up to 154 characters: 


9876 WINCHESTER BLYD. 





Pressing (ATTN) or (ENTER) will return to the original Data Browser 
display. 


Editing Data Items. If the edit_flag is non-zero, pressing 
(4) presents the command line editor: 


LESKIPIZKIPS/€UEL [OELS LIN? a] | 





The menu keys are identical to the command line editor, but the 
stack is not available. User key definitions and HP 48 menus may 
be used. The edit session can be aborted by pressing [ATTN], or 
the new data can be accepted by pressing (ENTER). There are 
two important points to consider about editing data items: 
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e The new data is checked for proper syntax, and must result 
in a legitimate object. For instance, if the new data 
represents a program, it must be syntactically correct. 
String data objects must be surrounded by quotes. 


e If edit_flag is negative, no type-checking occurs. If the 
results of the browser session are destined for a type- 
dependent procedure, such as filling a numeric array, it 
may be wise set edit_flag positive to check the user’s input. 


Searching for Data. Pressing [a] produces a prompt for a 
search string: 


< HOME 
Search for: 





#SEIPISEIPS] €CEL [GELS TINZ |_| 


The menu keys are identical to the command line editor, but the 
stack is not available. User key definitions and HP 48 menus may 
be used. The search prompt can be aborted by pressing [ATTN], 
or the search string can be accepted by pressing (ENTER). 


The search begins just past the current data item, and wraps 
around if necessary. The search ends at the first data item found 
that contains the search string. Labels are ignored during the 
search. 
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Example: The “address list" example on the first page of this 
chapter was illustrated using the following program: 


NAMES (308 bytes, checksum #2C49h) 


& 


% 
y 


£ 
t 
co 
= 


= 


"Mbr#: ""Namet " "Addr? " "City: " 
"St Hy u "Vip s " "PRE s u "Dates: u 


47 

"JOE SMITH" 
"123 ANYSTREET" 
"CORVALLIS" 

u oR u 

97338 
"383-555-1212" 
11.241959 


"op" "BEL u uu ui uu u QUIT" Hy 
2231" ADDRESS LIST" 3} 


TD DBR 


Note that in this example, the first row has been set to two and 
current row has been set to three, so that the name appears first 
at the top of the display and the pointer is set to the address line. 


Data Browser 
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Example: The program LUNCH on the next page illustrates a 
small application that uses the Data Browser and four Tool Library 
commands: EXTRACT, NXTOB, PRVOB, and REPLACE. 


Select Your Lunch: 
+Coursel: 

Course2: F 

Fruit & 


Dessert: 
Drink =: Cola 


LPREW |NE:T | 





While the program LUNCH is running, the PREY and HET. 
keys may be used to change the selection for each of five 
categories. For instance, pressing NET with the pointer on 
the "Fruit" line selects the next available fruit selection: 








Select Your Lunch: 
Coursel: Cheeseburger 
Course2: Fries 

2Fruit =: Apple 
Dessert: ice Cream 
Drink |= Cola 


LPREY |NEXT | LP eHUIT 








The program is terminated by pressing either GUI 
[ATTN]. The selections are returned in a list: 


ENTER}, or 


< HOME + 


1: { "Steak" "Salad" 


ygran e" 
nece ream" 
Coffee 

PHRT =| PROE | HYP [MATRIYECTR) EWE | 
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LUNCH (733.5 bytes, checksum #C4ACh) 


= 
£ 
{ "Cheeseburger" "Steak" "Chicken" "Hot Dog" 3 
£ "Fries" "Salad" "Baked Beans" "Corn" + 
{ "Orange" "Apple" "Banana" "Pear" } 
£ "Ice Cream" "Yogurt" "Cookies" 3} 
£ "Cola" "Coffee" "Milk" "Water" 3 
+ 
"Coursel: " "Course2: " "Dessert : " 
"Fruit =: " "Drink =: " 


3 
OVER LIST? 1 EXTRACT +LIST 1 
+ Choices Labels Lunch Running 


* 


{£211 6 "Select Your Lunch:i" 3} 
WHILE Running 
REPEAT 
Labels Lunch 
t 
"PREY" "NEXT" "NULLEEY 
"MNULLKEY "HULLKEY" "QUIT" 


3 
4 ROLL DBR 
IF 
DUP -6 SANE OVER 6 = OR 
THEW 
3 DROPH Lunch @ 'Running' STO 
ELSE 
Lunch 3 PICK GET Choices 4 ROLL GET 
OVER 4 ROLL 


IF -1 SAME THEN PRYOB ELSE NXTOB EHD 
Lunch 3 ROLLD REPLACE 'Lunch' STO 
END 
END 


as 


2 
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Title Browser 


The Title Browser is a utility which provides an efficient method 
for presenting a series of names or choices to the user with a 
definable set of menu keys. 


The Title Browser appears to the user as three columns of titles 
with a movable underscore to indicate a choice: 


Choose a planet: 
Ba 
SHTURN JUPITER 


[MARS | 
BE SS 





LEUN [HOON | TEMP OREIT 


In the display above, there are nine choices available. If there are 
more than fifteen choices, the title bar will be changed: 


f=] Choose a number? | 





ee ee 


The display above shows the order in which the choices are 
displayed from the input list. The arrows in the upper-left corner 
of the display indicate that more data items reside above and 
below those shown in the display. 
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Input Parameters 
The input parameters to the Title Browser are three lists: 


Level3: < data list + 


This list contains the objects which will be presented as 
the data. The objects will be converted to a string and 
centered within the highlighted screen areas. The list 


must contain at least one object. 


Level 2: £ menu label list 3 


This list contains the objects which will be presented as 
menu labels. If the label object is an empty string the 
menu label will be black and the menu key will generate 
an error beep when pressed. If the label object is the 
string "NULLKEY" the menu label will be white and the 
menu key will generate an error beep when pressed. A 
21x8 graphics object may will be used for the key label 
(see Menu Label Builder). An empty list is acceptable, 


but the display will still show black labels. 


Level 1: <{ current_item first_row title > 


The real number current_item specifies the index in the 
data list indicated by the underscore. The real number 
first_row specifies the first row of data elements to 
appear in the display. If first_row specifies a row that 
would force the last row of data to appear above the 
bottom of the display, the value is adjusted to place the 
last row of data at the bottom of the display. If the 
underscore is off-screen relative to the first_row, the 
data is positioned to place the pointer in the display. 
The title is specified by a string. Long titles will be 
truncated to 21 characters. If there are more then 15 
data items, only 20 characters will be displayed, in 


order to make room for the arrows. 


Title Browser 


Output Parameters 
The results from the Title Browser are three items: 


Level 3: 


Level 2: 


Level 1: 
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< current_item first_row title 3 

This list is similar to the level 1 input list. The real 
number current_item is the index in the data list of the 
underscored data item when the Title Browser 
terminated. The real number first_row specifies the 
first row of data elements that appeared in the display 
when the Title Browser terminated. The title is the 
same as the input parameter. 


current_item 

The real number current_item is the index in the data 
list of the underscored data item when the Title 
Browser terminated. 


terminator_key 
The terminator_key indicates how the user terminated 
the Title Browser: 


0: Zero is returned when the user presses [ATTN]. 
1: One is returned when the user presses (ENTER). 


-n: If the result is a negative number, the absolute 
value indicates which menu key was pressed. 


Title Browser 


Active Keys 


While the Title Browser is running, the following keys are active: 


(4) (Y) &) 





ENTER 


ATTN 


Example 


The arrow keys may be used to move the 
underscore. Press [¢] (4) or [4] [¥] to 
move the underscore one screen at a time. 
Press [p>] [4] or [>] [¥) to move to the ends 
of the catalog. 


Pressing a non-null menu key will terminate 
the Title Browser, indicating which menu key 
was pressed and which item was 
underscored. 


Terminates the Title Browser with a 1, 
indicating which item was underscored. 


Terminates the Title Browser with a 0, 
indicating which item was underscored. 


The "planets" example at the beginning of this chapter was 
illustrated using the following program: 


PLANETS (223 bytes, checksum #4A3Fh): 


on 


"MERCURY" 
"JUPITER" 


tat 


ate 


TER 


Title Browser 


"VEHUS" "EARTH" "MARS" "SATURH" 
"URAHUS" "NEPTUHE" "PLUTO" 


"SUN" "MOON" "TEMP" "DIST" "ORBIT" "QUIT" 3 
11" Choose 35 planet: " 4 


Tool Library 


The Tool Library provides 74 new commands that extend the 
built-in command set of the HP 48. The new commands fall into 
the following categories (see Command Index): 


e Array Operations. Ten commands facilitate the addition, 
deletion, exchange, or replacement of rows and columns in 
an array. 


Graphics. Eight commands provide pixel manipulation for 
graphics objects on the stack, coordinate conversions, and 
graphics object rotation. 


List Manipulation. Twelve commands perform list 
decomposition, manipulation, and sorting. 


Meta-Object Utilities. Fourteen commands provide tools 
for manipulating meta -— objects. 


Set Utilities. Six commands manipulate lists as sets. 


Stack Manipulation. Seven commands perform § stack 
movement and sorting. 


String Manipulation. Twenty-two commands _ perform 
extensive string manipulations. 


Other Commands. Two commands calculate the day of the 
week or the day of the year given a date. Two commands 
extract variable names from a program or equation and 
search user memory for variables by name or type. The 
XTIME command calculates execution times. 
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Graphics 

The graphics commands in the Tool Library use pixel coordinates 
to identify a pixel in a graphics object. A pixel coordinate consists 
of a list containing two binary integers, { #co/ #row }. 


The upper-left pixel of a graphics object is represented by 
{ #0 #0 }. Graphics objects placed into or extracted from PICT 
with the built-in commands GOR, GXOR, SUB, or REPL are 
located by their upper-left corner. Similarly, the Tool Library 
commands PXOFF, PXON, and PX? assume that the upper-left 
pixel of a graphics object is { #0 #0 }. 


HP 48 Display Coordinates 


{ #0 #0}, { #130 #0 } 





{ #col #row } r_] 


{ #0 #63 } 0 { #130 #63 } 


The built-in commands PX—C and C-PX convert between user 
coordinates, such as (x,y), and pixel coordinates. The Tool 
Library commands PX-R and R-PX simplify the translation 
between pixel coordinates and loop indices or calculation results. 


Example: The following program fragment (64.5 bytes, 
checksum #6331h) draws a dotted line in PICT. The command 
R—PxX is used to form the pixel coordinate for PIXON. 


% 
8 62 FOR i i 2 *# i R4+PX PIXOH 2 STEP { 3 PVIEW 
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Set Utilities 

The set utilities assume (but do not require) that a set is defined 
as a list of unique objects. In combination with other commands, 
the set utilities can simplify some otherwise complicated 
procedures. 


A set on the stack may be as simple as an empty list, or a list of 
many different objects. The command —SET may be used to 
ensure that all the objects in a set are unique. The command 
ADJOIN adds an object to a list only if the object does not appear 
in the list. 


The commands DIFF, INTERSECT, SDIFF, and UNION perform 
set operations or comparisons. 


Example: Variables From Equations. The following program 
fragment (49 bytes, checksum #81A2h) uses the set utility 
UNION and the command EQNVARS to return a list of all the 
variables used by a list of equations: 


& 
OBJ? MREVERSE ¢ 3 
1 ROT 
START 
SWAP EQHNVARS DROP UNIOH 
NEAT 
* 


In the example above, the UNION command is used to ensure 
that the variables found are added to the output list only if they 
are unique. The MREVERSE command is used here to reverse 
the order of the equations on the stack so the variables in the 
output list appear in the left-to-right order that you would read 
them in the input list. 
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Example: Finding Variables Containing Real Numbers. 

A complex directory structure can lead to confusion: where is a 
variable X which does not contain a real number? The following 
program fragment (43.5 bytes, checksum #5584h) uses the set 
utility INTERSECT and the command VFIND to return a list of all 
the variables named X that contain a real number: 


# 
'X' VFIND 3LIST & YFIND LIST INTERSECT 
2 


In the example above, each call to the VFIND command returns a 
list of paths. The INTERSECT command is used to ensure that 
only variables that do contain real numbers are returned. 


Example: Finding Variables NOT Containing Real Numbers. 
The following program fragment (43.5 bytes, checksum #96AQ9h) 
uses the set utility DIFF and the command VFIND to return a list 
of all the variables named X that do not contain a real number: 


'A' VFIHD +LIST & YVFIHD +LIST DIFF 
+ 
In the example above, each call to the VFIND command returns a 


list of paths. The DIFF command is used to ensure that only 
variables that do not contain real numbers are returned. 
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Meta-— Objects 

The term meta-object refers to a group of objects and their 
count that resides on the stack. Since stack operations are by 
nature very efficient, there will be instances when manipulating 
groups objects on the stack is more efficient than keeping the 
objects in lists. The meta-—object utilities presented below 
condense the stack operations into efficient system -— code. 


The following display shows a meta-object consisting of three 
objects and their count: 


= 
co 
= 
m 
Lal 


t 
4 
3 
2 
il 





Gas oe Se a a ee 


The term meta-stack refers to a group of objects on the stack, 
some of which may be meta- objects. The term position is used 
instead of level when discussing meta-stacks, because a meta- 
object actually occupies multiple stack levels. 


The following meta-stack consists of the complex number (3,4) 
in position 1, and meta-— objects in positions 2 and 3: 


"MARS" "JUPITER" 2 219 69 3 C3545 
Position 3 Position 2 Position 1 
Notation 
To simplify discussions about meta-objects, the following 
notation is presented. The count is always assumed to be below 
the elements on the stack. 
Stack Notation. The following symbols are used to indicate 


objects and meta-objects on the stack, where the right- most 
element is at the bottom of the stack: 
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<> 


< obj, objo obj > 


<... > Obj 
< obj... > 
< ... Obj > 


< metas > < meta, > 


An empty meta-object on the stack 
(which is just a 0, because the meta— 
object must have a count). 


An arbitrary meta-— object on the stack. 


A meta-object composed of three 
objects. 


An object in level 1 and a meta-— object 
beginning at level 2. 


A meta-— object on the stack, with obj at 
the head. The head is the element 
farthest from the count. This is 
equivalent to the decomposition of the 
list { Obj ... }. 


A meta- object on the stack, with obj at 
the tail. The tail is the element closest to 
the count. This is equivalent to the 
decomposition of the list { ... obj }. 


Two meta -— objects on the meta-— stack. 


Utility Names. The meta- object command names start with M, 
for Meta-— object, and use the following naming convention: 


Refers to a list. 


| MNOATrFZO> 
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Refers to the addition of an object to a meta -— object. 
Refers to the deletion of an object from a meta-— object. 
Refers to a meta -— object. 


Refers to the head of a meta -— object. 
Refers to the tail of a meta— object. 
Refers to an empty meta -— object. 
Refers to the meta-— object in position 2. 


The phrase "to" (converting to another form). 
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Utilities 


To establish an empty meta-object on the stack, just place a 
zero in level 1. To convert a list or vector into a meta-— object, 
execute OBJ—. To convert a meta- object back to a list, execute 
—LIST. To convert a meta—object back to a vector, execute 


—ARRY. 


The meta-— object utilities, described in the command reference, 
consist of the following commands: 


MDH2 


MDT 

MDT2 
ML—M 
MM-L 
MREVERSE 
MSWAP 
MZ2 


Adds an object to the head of a meta-—obj in position 1 
Adds an object to the head of a meta-obj in position 2 
Concatenates two meta -objs 

Adds an object to the tail of a meta—obj in position 1 

Adds an object to the tail of a meta—obj in position 2 
Extracts an element from the head of a meta-obj in pos. 1 
Extracts an element from the head of a meta -—obj in pos. 2 
Extracts an element from the tail of a meta—obj in pos. 1 
Extracts an element from the tail of a meta—obj in pos. 2 
Converts lists in positions 1 and 2 into meta-—objs 
Converts meta -objs in positions 1 and 2 into lists 
Reverses the order of the objects in a meta -obj 

Swaps the meta -objs in positions 1 and 2 

Places an empty meta -—obj in meta-stack position 2 





Other commands in the Tool Library that accept or return 
parameters in the form of meta-— objects are: 


EXTRACT 
LSORT 
QSORT 


VFIND 
—WORDS 


Returns the mth element from n lists 

Sorts a series of n lists based on the mth element 
Sorts a series of objects 

Finds variables in user memory 

Separates a string into individual words 
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Example: Testing Variables. If the variables used by a program 
or equation depend upon the initial conditions of certain 
variables, a program to show which variables exist in the current 
path may be helpful. 


The following program expects an equation or program as input 
and returns lists indicating which global variables are defined and 
undefined. The program uses the meta-object utilities MZ2, 
MDT, MAH, MAH2, and MM--+L. The undefined variables are kept 
in position 1, and the defined variables are moved to the meta- 
object in position 2. 


ESCAN (161 bytes, checksum #8B5Dh) 
« 
EGHVARS DROP DTAG Get global variables 
OBI+ Explode list for count 
IF CUP THEM Process if there are some global vars 
M22 DUP 1 SWAP 


START 
MOT DUP YTYPE 
IF -1 SAME Does variable exist? 
THEH If nonexistent, 
MAH and add to “undefined" meta-obj. 
ELSE 
MAH2 If exists, add to “defined” meta-obj. 
EHD 
HEXT MM4L Convert meta-obs to lists. 
ELSE 
DROP If there were no global variables, 
{ 3 3 retum two empty lists. 
EMD 
"Undefined" +TAG SWAP Add tags. 


"Defined" TAG 
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Temporary Memory 

A large part of the motivation for using meta— objects has to do 
with the use of temporary memory in the HP 48. The stack in the 
HP 48 is actually a stack of pointers which refer to objects 
elsewhere in memory. Temporary memory is the calculator’s 
“scratchpad”. All objects that are not stored in a port or in a user 
variable reside in temporary memory. Many commands require 
temporary memory to construct intermediate objects or new 
objects returned as results to the stack. 


Use of Temporary Memory 

To understand temporary memory a little more, consider what 
happens when two math operations are performed. Enter the 
numbers 1.5 and 2.6 on the stack. These numbers now reside in 
temporary memory, referred to by pointers on the stack. When 
the numbers are added, the result, 4.1, is a number in temporary 
memory referenced by a pointer in level 1 of the stack. The 
objects 1.5 and 2.6 remain in temporary memory, referenced by 
pointers that point to the Last Arguments. 


Now add 2.8 to the result in level 1. The level 1 pointer on the 
stack refers to the object 6.9 in temporary memory. The Last 
Arguments pointers now refer to the objects 2.8 and 4.1, and the 
objects 1.5 and 2.6 are no longer referenced. 


Garbage Collection 

From time to time the HP 48 will “hesitate” during an operation. 
This hesitation is usually caused by the removal of objects in 
temporary memory which are no longer being used. Objects 
which are no longer referenced continue to accumulate in 
temporary memory until memory has been filled. When memory 
is full, the calculator scans the objects in temporary memory, 
deleting those without references to them. This process, known 
as "garbage collection", is similar in concept to garbage collection 
in LISP. 


A large number of pointers on the stack that point to temporary 
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memory can slow down the garbage collection process to an 
uncomfortable degree. This occurs when there are a large 
number of objects on the stack, or an object has been extracted 
from a large list. List operations can be optimized by storing the 
lists in global variables, effectively moving the operations from 
temporary memory to user memory. 


The MEM command returns the amount of available memory, 
forcing an initial garbage collection to return an accurate result. It 
may be helpful to insert the sequence MEM DROP to force 
garbage collection prior to speed -— sensitive program sequences. 


The NEWOB Command 

The command NEWOB may be used to create a new copy of an 
object in temporary memory, whose only reference is on the 
stack. In general, the system will perform an automatic NEWOB 
where it makes sense. For instance, if you recall the contents of a 
variable to the stack and press , the object will be copied to 
temporary memory before editing begins. There are three 
situations in which NEWOB can be used explicitly for better 
control of temporary memory usage: 


e NEWOB "frees" an object that was extracted from a list. 
Consider the following program: 


« € "AB" "CD" "EF" > 2 GET » 


After executing this program, level 1 of the stack contains a 
pointer into the list, which still resides in temporary memory. 
Executing NEWOB now would create the unique object 
"AB" in temporary memory, and release the list for garbage 
collection. Note: Set the Last Arguments flag (-—55) to 
prevent the list from being referenced as one of the GET 
command’s arguments. 
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e Recalling an object to the stack places a pointer to the 
object on the stack. In the case of backup objects in a port, 
which consist of an object, name, and checksum combined 
into a single object, recalling it to the stack places a pointer 
to the object within the backup object on the stack. This is 
why the system does not do an automatic NEWOB. To 
purge a backup object from a port while retaining a copy in 
temporary memory, recall it and execute NEWOB. Then the 
backup object may be purged because there are no 
references to it. 


The commands PXON and PXOFF in the Tool Library 
modify the graphics object directly without creating a copy. 
If there are several pointers on the stack to a graphics 
object modified by PXON or PXOFF, each of those pointers 
will point to the changed graphics object in memory. The 
NEWOB command may be used in this situation to ensure 
there are no other references to the graphics object being 
changed. 
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Command Index 
This index lists the commands in the Tool Library, grouped into 
subject areas. Some commands or functions appear more than 


once. 

ARRAY OPERATIONS 

DELCOL Deletes a column from an array 

DELROW Deletes a row from an array 

EXCOL Exchanges two columns in an array 

EXROW Exchanges two rows in an array 

GETCOL Extracts a column from an array 

GETROW Extracts a row from an array 

INSCOL Inserts a column into an array 

INSROW Inserts a row into an array 

PUTCOL Replaces a column in an array 

PUTROW Replaces a row in an array 

GRAPHICS 

PX+ Adds two graphics pixel coordinates 

PX- Subtracts two graphics pixel coordinates 

PXOFF Clears a pixel in an arbitrary graphics object 
PXON Sets a pixel in an arbitrary graphics object 

PX? Tests a pixel in an arbitrary graphics object 
PX-—R Converts pixel coordinates into two real numbers 
ROTATE Rotates a graphics object 

R-—PX Converts two real numbers into pixel coordinates 
LIST MANIPULATION 

CAR Returns the first object of a list 

CDR Returns a list minus its first object 

CUT Splits a list into the first and remaining objects 
EXTRACT Returns the mth element from each of a series of lists 
LSORT Sorts a series of lists based on the mth element 
NXTOB Returns the next choice from a list of choices 
PRVOB Returns the previous choice from a list of choices 
SPLIT Splits a list into two lists 

REPLACE Replaces all occurrences of an object in a list 
REVERSE Reverses the order of objects in a list 

ROTATE Rotates the objects in a list 

—SET Removes duplicate objects from a list 
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META-OBJECT UTILITIES 


MAH Adds an object to the head of a meta-—obj in position 1 
MAH2 Adds an object to the head of a meta-obj in position 2 
MAM2 Concatenates two meta-objs 

MAT Adds an object to the tail of a meta-obj in position 1 
MAT2 Adds an object to the tail of a meta—obj in position 2 
MDH Extracts an element from the head of a meta-obj in pos. 1 
MDH2 Extracts an element from the head of a meta-obj in pos. 2 
MDT Extracts an element from the tail of a meta-—obj in pos. 1 
MDT2 Extracts an element from the tail of a meta-obj in pos. 2 
ML—M Converts in lists positions 1 and 2 into meta—objs 
MM—L Converts meta -obs in positions 1 and 2 into lists 
MREVERSE __ Reverses the order of the objects in a meta-obj 
MSWAP Swaps the meta-objs in positions 1 and 2 

MZ2 Places an empty meta -—obj in meta-stack position 2 
SET UTILITIES 

ADJOIN Adds an object to a list if it is unique 

DIFF Returns the set difference of two lists 

INTERSECT __ Returns the set intersection between two lists 

SDIFF Returns the set symmetric difference of two lists 

—SET Removes duplicate objects from a list 

UNION Returns the set union of two lists 

STACK MANIPULATION 

KEEP Keeps the bottom n objects on the stack 

MREVERSE _ Reverses the order of the first n stack objects 

NDUP Creates n copies of an object 

QSORT Sorts n objects on the stack 

SRLL Rotates n objects on the stack up m times 

SRLLD Rotates n objects on the stack down m times 

SXCH Exchanges objects at levels m andn 
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STRING MANIPULATION 


CAR Returns the first character of a string 

CDR Returns a string minus its first character 

CUT Splits a string into the first and remaining characters 
ICAPS Converts the words in a string to initial caps 

LCASE Converts the characters in a string to lowercase 
LTRIM Removes leading spaces and tabs from a string 
PUTCHR Places character code n in a string 

REPLACE Replaces all occurrences of a substring in a string 
REVERSE Reverses the order of characters in a string 

ROTATE Rotates the characters in a string 

RPTSTR Creates a string of n substrings 

RTRIM Removes trailing spaces and tabs from a string 
SPLIT Divides a string into two strings 

—STDSTR Converts an object to a string in standard display mode 
STRCON Rapid creation of new character strings 

STRCTR Centers a string in a specified number of spaces 
SUBNUM Returns the character code of a string’s nth character 
TIO Converts a string to its translated form for |/O 

TIO> Converts a string from its translated form for |/O 
TRIM Removes leading and trailing spaces and tabs from a string 
UCASE Converts the characters in a string to uppercase 


—WORDS Separates a string into individual words 


OTHER COMMANDS 

DOW Returns the day of the week given a date 

DOY Returns the day of the year given a date 

EQNVARS Returns a list of global variables in an equation or program 
VFIND Find all occurrences of a variable or object type in user memory 
XTIME Calculates execution times 


Error Messages 
The Tool Library contains four new error messages: 


[Hex [Dec | __Ewror Message 


198657 Invalid Pos 1 Meta- Obj 
198658 Invalid Pos 2 Meta— Obj 


198659 Empty Meta- Obj 
198660 Inconsistent Data 
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Command Reference 


This command reference lists the stack diagrams for each of the 
commands in the Tool Library. Each entry lists the name, 
description, and stack diagrams. An example is provided to show 
how each command works. 


Input Output 


Level, Level, Level, -—+ Level; Level, Level, 





The following table lists the terms used in the stack diagrams. Note 
that system modes may affect the interpretation of input parameters 
or the results of some functions. 


obj Any object 

xory Real number 

(xy ) Complex number 

z Real or complex number 

morn Positive integer real number (rounded if non-integer) 
#n or #m Binary integer 

"string" Character string 

"chr Character string containing only one character 
{list} List of objects 

grob Graphics object 

{ #x #y} Pixel coordinates 

date Date in current date format 

meta Meta —object (see Meta - Objects) 

type Object type (see Object Types) 

[vector] Real or complex vector 

[[matrix]] Real or complex matrix 

‘global’ Global name 

T/F Test result: 0 (false) or non-zero (true) 





Meta - object utilities are described with a notation presented 
in Meta — Objects. 
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ADJOIN 


Adds an object to a list if the object is not a member of the list. 


ADJOIN 
{list,} obj —> {list} 


Examples: 
{ 11 22 33335 —- ¢ 11 22 33 3 


€ 11 22 33 3 44 -— ¢€ 11 22 35 44 3 


Related Commands: DIFF, INTERSECT, SDIFF, -—SET, 
UNION 
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CAR 

The command CAR may be used to extract the first element of 
a list or the first character from a string. When a list object is 
extracted, a NEWOB is performed to free the element from the 
list (see Temporary Memory). 


"string," “strings” 


{obj, ... 





Examples: 


"ABCD" —. "AN 


Related Commands: CDR, CUT, EXTRACT, NXTOB, PRVOB, 
SPLIT, REPLACE, REVERSE, ROTATE, SET 
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CDR 


The command CDR may be used to remove the first object 
from a list or the first character from a string. 


"string," "strings" 


{ } { } 
{obj, ... obj,} {objp ... obj} 





Examples: 


"RBCE" —> "BCDB" 


Related Commands: CAR, CUT, EXTRACT, NXTOB, PRVOB, 
SPLIT, REPLACE, REVERSE, ROTATE, —SET 
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CUT 


The command CUT may be used to split a list or string into the 
first and remaining components. 


When a list object is extracted, a NEWOB is performed to free 
the element from the list (see Temporary Memory). 


"string," “string” “chr” 


{ } {} {} 
{obj, ... obj,} {obj, ... obj} obj, 





Examples: 
"RBCD u => u Bco" a = i 


£39823 74 {3823 3 


Related Commands: CAR, CDR, EXTRACT, NXTOB, PRVOB, 
SPLIT, REPLACE, REVERSE, ROTATE, -SET 
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DELCOL 


The command DELCOL may be used to delete a column from 
a vector or matrix. The vector or matrix must have at least two 
columns. 


DELCOL 


[vector,] n — [vector,] 
[[matrix,]] n — [[matrix.]] 





Examples: 
c39821]1 3 > [—892] 
CC 11 22 33 ] CC 11 33 ] 


— 
4455 66 ]] 2 C 44 66 J] 


Related Commands: DELROW, EXCOL, EXROW, GETCOL, 
GETROW, INSCOL, INSROW, PUTCOL, PUTROW 
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DELROW 
The command DELROW may be used to delete a row from a 
matrix. The matrix must have at least two rows. 


DELROW 
[[matrix,]] n — — [[matrix,]] 
Example: 
CC 11 22 33 ] CC 11 22 33 ] 
44 55 66 J] 2-4 C rr 86 99 ]] 
rr 68 99 J] 


Related Commands: DELCOL, EXCOL, EXROW, GETCOL, 
GETROW, INSCOL, INSROW, PUTCOL, PUTROW 
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DIFF 


Returns the set difference of two lists. 


DIFF 
{list} {list}} — — {lista ano Not bt 


Examples: 
C{i123943f563 > €1234 3 


Cle2e2e3s¢3€3457 7-4 C12 3 


Related Commands: ADJOIN, INTERSECT, SDIFF, —SET, 
UNION 
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DOW 


Returns the day of the week given a date in the current date 
format. The days are numbered starting with Monday=1, 
Tuesday=2, etc. The earliest valid date for this function is 
October 15, 1582. 


DOW 


date — n 


Examples: 
3.181957 — 6 


3.251981 —- 1 


Related Command: DOY 
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DOY 

Returns the day of the year given a date in the current date 
format. The earliest valid date for this function is January 1, 
1583. 


DOY 


date — n 


Examples: 
5.181957 — 138 


3.231981 —-4 82 


Related Command: DOW 
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EQNVARS 

Given a program or equation, EQNVARS returns lists of global 
and local variables used in the program or equation. If the 
input to EQNVARS is a global name, the contents of the name 
must contain an equation or program, and that object will be 
scanned for variables. 


EQNVARS 


« program » Global:{ names } Local:{ names } 


‘equation’ Global:{ names } Local:{ names } 
‘name’ Global:{ names } Local:{ names } 





Examples: 
'Be4! — Global: €£ + Local: { + 
"Raf cKn*e+ 7 "2! — Globsl: £€ RF # VY 3 Local: ¢ 


kee uy xe 2% yY 2 * + J 'R' STO % & A 
Global: £ F } Local: £ x y 3 


Note: The built-in Solver in the HP 48 performs a recursive 
search through variables to find named programs or 
equations and adds variables found in those objects to the 
Solve menu. EQNVARS only searches the program or 
equation itself. Therefore the variables returned by EQNVARS 
may be a subset of the variables displayed by the Solve menu. 
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EXCOL 


Exchanges two columns in an array. 


EXCOL 


vector,] col, col, — vector 
1 1 2 2 





[[matrix,]] col, col — [matrix.]] 


Examples: 
Ci2es34¢1]1 e235 -—> Cigse4] 


[(Ciedyct34¢i]]1e2 7 (L2e1i11043]] 


Related Commands: DELCOL, DELROW, EXROW, GETCOL, 
GETROW, INSCOL, INSROW, PUTCOL, PUTROW 
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EXROW 


Exchanges two rows in an array. 


EXROW 


[[matrix,]] row, row. — [matrix]] 


Example: 


[(CiedygC€34i]] 12 7> [£3 41012 ]] 


Related Commands: DELCOL, DELROW, EXCOL, GETCOL, 
GETROW, INSCOL, INSROW, PUTCOL, PUTROW 
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EXTRACT 

The command EXTRACT may be used to return the mth 
element from each of a series of n lists. The input and result 
are formed as meta- objects. A NEWOB is performed to free 
each element from the list (see Temporary Memory). 





Example: 


{3 91 301783068 12332 74 31 75 123 


Related Commands: LSORT, MREVERSE 
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GETCOL 


Returns a column from an array as a matrix consisting of 1- 
element rows. 


GETCOL 


[vector] col — [[column data]] 
[[matrix]] col — [[column data]] 





Examples: 


[(Ci2z3s3].C4561]] 2 — [CC 2°] £€ 5S: Jd] 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETROW, INSCOL, INSROW, PUTCOL, PUTROW 
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GETROW 


Returns a row from an array as a vector. 


GETROW 


[vector] row — [row data] 
[[matrix]] row — [row data] 





Examples: 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETCOL, INSCOL, INSROW, PUTCOL, PUTROW 
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ICAPS 


Converts the first character of each word in a string to 
uppercase, and the remaining characters to lowercase. The 
separation characters are any character code <30, 32, and 
160. 


ICAPS 


"string," — = “strings” 
The case conversion supports the ISO 8859-1 character set 
in the following ranges: 


Lowercase Uppercase 


61h-7Ah +— 41h-5Ah 


EOQh-F6h +— COh-D6h 
F8h-FEh +— D8h-DEh 





Examples: 


"JOHH SMITH" — “John Smith" 


“sample sentence" — "Sample Sentence 


Related Commands: LCASE, UCASE 
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INSCOL 

The command INSCOL may be used to insert a column into 
an array. The column number specifies which column will be 
zero-filled, and may be one greater than the number of 
columns in the array. 


INSCOL 


[vector,] n [vector,] 
[[matrix,]] n [[matrix.]] 





Examples: 
C3982] 383 > [39682 ] 


C ¢9,49 €8;39 7 3 - C €9,43 €6,5) (6,63 J] 


CC 11 22 33 ] CC ii @ 22 33 J] 
44 55 66 ] or = C 44 6 355 66 ] 
rr 88 99 J] C fr 8 88 99 J] 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETCOL, GETROW, INSROW, PUTCOL, PUTROW 
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INSROW 

The command INSROW may be used to insert a row into an 
array. If the input is a vector (one-dimensional), the result will 
be a matrix (two-dimensional). The row number specifies 
which column will be zero-filled, and may be one greater 
than the number of rows in the array. 


INSROW 


[vector] n — [[matrix]] 


[[matrix,]] n —> — [[matrix,]] 





Examples: 
—- [C6666 ] 

3 
; een ot end C396 2 ]] 
CC ii 22 33 J] CC 11 22 33 J] 
44 55 66 J] 4 — C 44 55 66 ] 
Yr 68 99 J] C fr 66 99 J 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETCOL, GETROW, INSCOL, PUTCOL, PUTROW 
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INTERSECT 


Returns the set intersection between two lists. 


INTERSECT 


{list,} {list}} — = {lista anno b} 


Examples: 
{12343563 74 ¢ 3 


Cl23s¢30(3457 + €34 3 


Related Commands: ADJOIN, DIFF, SDIFF, -SET, UNION 
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KEEP 


Keeps the bottom n objects on the stack while deleting all 
objects above n. 





Example: 


"AR" 32 7.1 "B" 2 —- 7F.1 "B" 


Related Commands: NDUP, SRLL, SRLLD, SXCH 
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LCASE 


Converts each character in a string to lowercase. 


LCASE 


“string,” — = "strings" 


The case conversion supports the ISO 8859-1 character set 
in the following ranges: 


Lowercase Uppercase 


61h-7Ah + 41h-5Ah 


EOQh-F6h + COh-D6h 
F8h-FEh + D8h-DEh 





Example: 


"SAMPLE SENTENCE" ad “sample sentence" 


Related Commands: ICAPS, UCASE 
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LSORT 


The command LSORT may be used to sort a series of rn lists 
based on the mth element of each list. The input and result 
are formed as meta -— objects. 


The mth object in each list must be of the same type and 
comparable with >. The lists are returned in ascending order 
(the largest at the bottom of the stack). Use MREVERSE after 
LSORT to produce a descending order result. The sort order 
for strings follows the ISO 8859-1 character set (see 
Character Codes). 


LSORT 
{list,} ... {list,} n m — {listo} ... {listo} on 


Example: 
C39 30173823381 
C€i7Fr3st 393823 83 


Related Commands: EXTRACT, MREVERSE, QSORT 
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LTRIM 
Removes leading space and tab (#09h) characters from a 
string. 


LTRIM 
“string,” —> = “string,” 
Example: 
"SAMPLE STRING " —+ "SAMPLE STRING " 


Related Commands: RTRIM, TRIM, ~WORDS 
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MAH 


Adds an object to the head of a meta-— object. 


meta, obj —>+ meta, 


<..> obj — < obj... > 





Example: 


213247399 -4 99 21 32 47 4 


Related Commands: MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, MDT2, ML—M, MM—-L, MREVERSE, MSWAP, 
MZ2 
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MAH2 


Adds an object to the head of a meta- object in position 2. 


meta, meta, obj —+ meta, meta, 





< meta, > <meta, > obj —+ <objmeta,> < meta, > 


Example: 


2132 22.3 4.7 299 4 99 21 323 2.3 4.7 2 


Related Commands: MAH, MAM2, MAT, MAT2, MDH, MDH2, 
MDT, MDT2, ML-M, MM-+L, MREVERSE, MSWAP, MZ2 
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MAM2 


Concatenates two meta - objects. 


meta, meta, obj — metaz,, 





<meta, > <meta,> —+ <meta,,, > 


Example: 


2132 47 37.3 4.8 2 - 21 32 47 7.3 4.8 5 


Related Commands: MAH, MAH2, MAT, MAT2, MDH, MDH2, 
MDT, MDT2, ML—M, MM-—+L, MREVERSE, MSWAP, MZ2 
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MAT 


Adds an object to the tail of a meta-— object. 


meta, obj —> meta, 
<..> Ob] — < ... Obj > 





Example: 


2132 47399 -— @21 32 47 399 4 


Related Commands: MAH, MAH2, MAM2, MAT2, MDH, 
MDH2, MDT, MDT2, ML—-M, MM-—L, MREVERSE, MSWAP, 
MZ2 
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MAT2 


Adds an object to the tail of a meta-— object in position 2. 


meta, meta, obj -—*+ meta,’ meta, 





<meta, > <meta; > obj —+ <meta, obj > < meta, > 


Example: 


#132 22.3 4.7 299 - 21 3299 3 2.3 4.7 2 


Related Commands: MAH, MAH2, MAM2, MAT, MDH, MDH2, 
MDT, MDT2, ML-+M, MM->L, MREVERSE, MSWAP, MZ2 
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MDH 


Extracts an object from the head of a meta-— object. 


meta, —+ meta, obj 





<obj... > — <... > Obj 


Example: 


99 21 32 47 4 7 21 32 47 3 95 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, 
MDH2, MDT, MDT2, ML-M, MM—L, MREVERSE, MSWAP, 
MZ2 
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MDH2 


Extracts an object from the head of a meta-—object in 
position 2. 


meta, meta; -—+ meta,’ meta, obj 





< obj meta, > <meta;> —* <meta,’> <meta, > obj 


Example: 


93 21 32 32.3 4.7% 2 - 21 3222.3 4.7 2 99 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDT, MDT2, MLM, MM-+L, MREVERSE, MSWAP, MZ2 
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MDT 


Extracts an object from the tail of a meta-— object. 


meta, —*+ meta, obj 





<..0bj > — <..> Obj 


Example: 


2132 47 994 - 21 32 47 3 99 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT2, ML—-M, MM-—-L, MREVERSE, MSWAP, MZ2 
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MDT2 


Extracts an object from the tail of a meta— object in position 2. 


meta, meta, -—+ meta,’ meta, obj 





< meta, obj > <meta;> — < meta,’ > < meta, > obj 


Example: 


2132 99 32.3 4.7 2 - 21 3222.3 4.7 2 99 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, ML—M, MM—L, MREVERSE, MSWAP, MZ2 
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ML—M 


Converts two lists into meta — objects. 


{list,} {list} —+ meta, meta, 





{list.} {list;} — < meta, > < meta, > 


Example: 


{ li 2230 3.1 4.2 5.1 3 — 
11 22 2 3.14.2 35.1 3 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, MDT2, MM—L, MREVERSE, MSWAP, MZ2 
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MM—L 


Converts two meta - objects into lists. 


meta, meta, —  {list,} {list,} 


<meta, > <meta,;> —  {list,} {list,} 





Example: 


11 2223.1 4.2 53.13 — 
€ 11 22 30 3.1 4.2 5.1 3 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, MDT2, ML-M, MREVERSE, MSWAP, MZ2 
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MREVERSE 


Reverses the order of n objects on the stack. This command 
will reverse the order of 5000 stack items about two seconds. 


MREVERSE 
obj, ... obj, n Obj, ... Obj, n 
meta, meta, 





< obj, Obj, obj, > < objz Objz obj, > 


Example: 


11 22.23.4125 74 23.1 .2 22 115 


Related Commands: KEEP, MAH, MAH2, MAM2, MAT, MAT2, 
MDH, MDH2, MDT, MDT2, ML-M, MM-—-L, MSWAP, MZ2, 
NDUP, SRLL, SRLLD, SXCH 
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MSWAP 


Swaps two meta- objects on the stack. 


MSWAP 


meta, meta, —* meta, meta, 


<meta, > <meta,;> — <meta, > < meta, > 





Example: 


ll 2223.1 4.2 35.13 — 3.1 4.2 5.1 3 11 22 2 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, MDT2, ML—>M, MM-—L, MREVERSE, MZ2 
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MZ2 


Places an empty meta - object in meta-— stack position 2. 


meta; —*  Metaempry meta, 





<meta,;> — < > <meta, > 


Example: 


3.14.2 5.13 4 63.1 4.2 5.1 3 


Related Commands: MAH, MAH2, MAM2, MAT, MAT2, MDH, 
MDH2, MDT, MDT2, ML-M, MM—L, MREVERSE, MSWAP 
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NDUP 
Creates n copies of an object on the stack. If n is zero, no 
objects will be returned. 


NDUP 
obj n — obj... obj 


Examples: 


3.13 -— 5.1 5.1 5.1 


Related Commands: KEEP, MREVERSE, SRLL, SRLLD SXCH 
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NXTOB 


Given a list of n objects and an object, NXTOB finds the 
location of the object in the list and returns the following 
object. If the object is found at the end of the list, the first 
object is returned. If the object is not found in the list, the 


same object is returned. 


NXTOB 


{obj, ... Obj,} Obj, 


Examples: 
{ 3 "FRED" 
{ 11 22 353 3 22 


€ 11 22 33 3 


a 


= 
2 


aed Objm+1 


Related Commands: CDR, CUT, EXTRACT, LSORT, PRVOB, 
SPLIT, REPLACE, REVERSE, ROTATE, —SET 
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PRVOB 

Given a list of n objects and an object, PRVOB finds the 
location of the object in the list and returns the previous 
object. If the object is found at the beginning of the list, the 
last object is returned. If the object is not found in the list, the 
same object is returned. 


PRVOB 
{Objy... Objn} Obj —% — Objmns 


Examples: 
{ 3 “FRED" —- "FRED" 
{£ 112233 3 22 —- ii 


€ 1122 33 3 i1 —- 


ao 


3 


Related Commands: CDR, CUT, EXTRACT, LSORT, NXTOB, 
SPLIT, REPLACE, REVERSE, ROTATE, —SET 
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PUTCHR 


Places a character at a specified position in a string. The 
character may be specified by a real number character code 
or by the first character in a string. In the second instance, 
PUTCHR is similar to REPL, except that only one character is 
changed. 


PUTCHR 


"string," position code — “strings” 


"string," position "string" — "string," 





The commands PUTCHR and SUBNUM are designed for 
applications requiring an index array for values less than 255. 
Using a string to store the indices as character codes saves 
considerable memory compared to other storage methods, 
such as lists or arrays. 


Examples: 
"JOHN" 3 65 — "JOAH" 


"JOHN" 3 "ABC" — "JOAN" 


Related Commands: STRCON, SUBNUM 
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PUTCOL 


Replaces a column of data in an array. 


PUTCOL 


[[matrix,]] col [[new-col]] — [[matrix.]] 


Examples: 
Ci2zsd1] 2 (CC 441]]3 —7 C1 443 7 
[(ci2sa])qC456])] 2CC 11 IW 22 j1—- 

[€C iii 310 4 2261] 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETCOL, GETROW, INSCOL, INSROW, PUTROW 
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PUTROW 


Replaces a row of data in an array. 


PUTROW 


[vector,] row [new-row] — [vectors] 





[[matrix,]] row [new-row] — [[matrix.]] 


Examples: 

Ci2e31] 1C4561] 74 [456] 

[(Ci2ezs3]C4#456]]32C07891]-—- 
[(Cies3g]gtC/Yso9]i 


Related Commands: DELCOL, DELROW, EXCOL, EXROW, 
GETCOL, GETROW, INSCOL, INSROW, PUTCOL 
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PX+ 


Adds two graphics pixel coordinates. 


PX+ 
{#; #2} {#3 #4} — {#113 #oi4} 


Example: 


{ #3d #7d 3 { #6d #id } — C #9d #8d 3 


Related Command: PX- 
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PX- 


Subtracts two graphics pixel coordinates. 


PX- 
{#, #2} {#3 #4} — {#1-3 #2-4} 


Example: 


{ #25d #54d 3 { #6d #id 3} -— Cf #17d #53d 3 


Related Command: PX+ 
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PXOFF 


Clears a pixel in an arbitrary graphics object. 


PXOFF 
grob {#, #y} — — grob’ 


Notes: 


e This command does not work for PICT. Use the 
command PIXOFF for clearing pixels in P/CT. 


e The upper-left pixel in a graphics object has the 
coordinate { #0 #0 } (see Graphics). 


e This command does not return a unique copy of the 
graphics object. You may wish to execute NEWOB first 
to ensure that the result is a unique object (See 
Temporary Memory). 


Example: 


GROB 8 2 a364 { #6d #id + — GROB 3S 2 4366 


Related Commands: PXON, PX? 
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PXON 


Sets a pixel in an arbitrary graphics object. 


PXON 
grob {#, #y} — — grob’ 


Notes: 


e This command does not work for PICT. Use the 
command PIXOFF for clearing pixels in P/CT. 


e The upper-left pixel in a graphics object has the 
coordinate { #0 #0 } (see Graphics). 


e This command does not return a unique copy of the 
graphics object. You may wish to execute NEWOB first 
to ensure that the result is a unique object (See 
Temporary Memory). 


Example: 


GROB 8 2 8368 { #6d #id + — GROB 8 2 83564 


Related Commands: PXOFF, PX? 
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PX? 


Tests a pixel in an arbitrary graphics object. 


PX? 
grob {#,y #y} — T/F 


Notes: 


e This command does not work for P/CT. Use the 
command PIX? for testing pixels in P/CT. 


e The upper-left pixel in a graphics object has the 
coordinate { #0 #0 } (see Graphics). 


Example: 
GROB 8 2 8366 { #6d #id 3 — 
GROB & 2 e364 { #6d #id 3? — 1 


Related Commands: PXOFF, PXON 
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PX—R 


Converts a list of two binary integers to two real numbers. 


PX—R 
{ #col #row} — — col row 


Example: 


{ #4d #18d > — 4 #18 


Related Command: R-PX 
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QSORT 

The command QSORT may be used to sort a series of n 
objects on the stack. The input and result are formed as 
meta — objects. 

Each object must be of the same type and comparable with >. 
The objects are returned in ascending order (the largest at the 
bottom of the stack). Use MREVERSE after QSORT to 


produce a descending order result. The sort order for strings 
follows the ISO 8859-1 character set (see Character Codes). 


QSORT 


obj, ...obj, n —+  obj2... obj2 n 


Examples: 
3238r4 7> 237534 


"FRED" "ANNE" "20E" 3 —- "ANHE" "FRED" "20E" 3 


Related Commands: LSORT, MREVERSE 
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REPLACE 

The command REPLACE may be used to replace all 
occurrences of a substring within a string or of objects within 
a list. String comparisons require an exact match. 


REPLACE 


“string,” "stringsearch’ "“StliNGyepi" —> “strings” 


{list,} ODjsearch Obj-ep! 3 {lista} 





Examples: 
"“JOHH" "H" "A"  —  “JOAH" 
"ABCED" "BY h—" —  "A-C-B" 
£193 9353 944 + £1 44 3 445 3 
fo Cl,sia 2.2 "fred" 44 3 "fred" #33d — 


{ €1,;19 2.2 #35d 44 3 


Related Commands: CAR, CDR, CUT, EXTRACT, SPLIT, 
REVERSE, ROTATE, —SET 
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REVERSE 
The command REVERSE may be used to reverse the order of 
characters in a string or objects in a list. 


Reversals of large lists will be significantly faster if the list was 
originally stored in a global variable. The time to reverse a 
large list is longer than the time required for the MREVERSE 
command, owing to the overhead of unpacking and re- 
packing the list objects. Reversing a 1000-element list 
originating from a global variable should take about three 
seconds. If the same list originates in temporary memory, the 
reversal could take several minutes. 


String reversals are accomplished at a rate near 12,000 
characters per second. 


REVERSE 


“string,” “strings” 


{ } 
{ obj, ... { obj, ... obj; } 





Examples: 
“ABCD u — "“DBCBA u 


Ci2es¢53 73> €54321 3 


Related Commands: CAR, CDR, CUT, EXTRACT, LSORT, 
SPLIT, REPLACE, ROTATE, —SET 
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ROTATE 

The command ROTATE may be used to rotate the contents of 
a list, string, or graphics object. The direction of rotation is 
controlled by the sign of x: 


Rotates left 
No change 


Rotates right 





Graphics objects are rotated 90° to the left for x<0, or 90° to 
the right for x>0. If |x| is greater than the length of the list or 
string, the rotation count will be calculated MOD the list or 
string size. 


ROTATE 


"string," x "strings" 


list, x list, 
grob, x grob, 





String Examples: 
uu By 
"ABCDE" 2 — £“DERBC" 
"ABCDE" -2 — £'"CDERB" 
List Examples: 
{ 3 32 + tf F 
€123457 24> €45123+%3 


Ci23433 4 7~ (345123 


Command Reference 93 


Graphics Examples: 


Graphic 21 x 8 -1 — Graphic 8 x 21 
Graphic 21 x 8 6 — £=Graphic 21 x 8 
Graphic 21 x 8 1 — Graphic 8 x 21 


*« "123" 2 4+GROB -1 ROTATE PICT STO ¢ 3} PYIEW 


* "123" 2 4+GROB 1 ROTATE PICT STO £ 3} PYIEW % 


Note: Rotation performance for graphics objects is reasonable 
for small objects, such as axis labels for graphs, however the 
algorithm for rotating graphics was optimized for space as 
opposed to speed. Consequently, rotating a 131x64 graphics 
object takes just under 15 seconds. The rotation requires 
enough free memory to construct a second temporary 
graphics object. 


Related Commands: CAR, CDR, CUT, EXTRACT, LSORT, 
NXTOB, PRVOB, SPLIT, REPLACE, REVERSE, —SET 
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RPTSTR 


Creates a string consisting of n repetitions of an input string. 
If only one character is to be repeated, the STRCON 
command will give faster performance. 


RPTSTR 


“string’ n — "string ... string" 


Examples: 
u ABC u 7] = uu 


"ABC" 3 — £'"ABCABCABC" 


Related Command: STRCON 


Command Reference 95 


RTRIM 


Removes trailing space and tab (#09h) characters from a 
string. 


RTRIM 
“string,” — = "string," 
Example: 
"SAMPLE STRING " —+ "“" SAMPLE STRING" 


Related Commands: LTRIM, TRIM, ~WORDS 
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R—PX 


Converts two real numbers to a list of two binary integers. 


R-—PX 
col row —> {#col #row } 


Example: 


45 37 — € #45d #37d 3 


Related Command: PX—R 
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SDIFF 


Returns the set symmetric difference of two lists. 


SDIFF 
{list,} {list}} — — {lista xorb} 


Examples: 
£1i234373f35363 74> €123456 3 


Ci23s43€3453 73> ¢{125 3 


Related Commands: ADJOIN, DIFF, INTERSECT, —SET, 
UNION 
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—SET 


Removes duplicate objects from a list. 


—SET 
{list;}} —> {listg} 


Examples: 
{12343 —- £12343 
{4123213 - {4123 3 
Related Commands: ADJOIN, INTERSECT, CAR, CDR, CUT, 


DIFF, EXTRACT, NXTOB, PRVOB, SDIFF, SPLIT, REPLACE, 
REVERSE, ROTATE, UNION 
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SPLIT 
The command SPLIT may be used to divide a list or string into 
first m and remaining components. 


“string,” "string," "string," 
{ } OS ae 
{obj, ... obj,} {Objnay-- Obj,} {Obj, ... Obj, y} 





Examples: 
"ABCDE" 8 => "ABCDE" uu 
"RBCBE u 3 —> u DE" "HecC" 


{ 3 


aw 
{ 

ra 
ue 
rs 
or) 


{398273 6 +4 {39 


co 
fw 
“J 
we 
ata 
uw 


{398273 2 > f82 


| 
+ 


343 9 3 


Related Commands: CAR, CDR, CUT, REVERSE, ROTATE 
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SRLL 


Rotates n objects on the stack up m times. 





Example: 


11 #2 38 445552 - 35 44 535 11 22 


Related Commands: KEEP, MREVERSE, NDUP, SRLLD, 
SXCH 
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SRLLD 


Rotates n objects on the stack down m times. 





11 22 33 445552 —- 44 355 11 22 35 


Related Commands: KEEP, MREVERSE, NDUP, SRLL, SXCH 
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—STDSTR 


Converts an object to a string (like -+STR), using STD display 
mode and a wordsize of 64 bits. 


—STDSTR 


obj — ~ "string" 


Examples: 
Assuming the current display mode is 2 FIX, execute ’z’ 
—NUM, then —STDSTR: 


3.14 — "3.14159265359" 


Assuming the current wordsize is 8 and HEX mode is set, 
enter # 123h. The wordsize of 8 causes the binary integer to 
be displayed as # 23h. To see the full value, execute 
—STDSTR: 


# 23h 4 "“# 123h" 
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STRCON 


Creates a string consisting of n repetitions of a character 
code. Strings are created at a rate nearing 20,000 characters 
per second. 


STRCON 


code n — "string" 


Examples: 
65 8 — mu 


65 16 — "AAARARAAAR" 


Related Commands: PUTCHR, RPTSTR, SUBNUM 
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STRCTR 


Centers a string in a specified number of spaces. If the 
number of spaces added is not even, the extra space will be 
added to the end of the string. 


STRCTR 
"string," n — = “strings” 
Example: 
"SAMPLE" 9 0 —  " SAMPLE " 
"SAMPLE" 14 — " SAMPLE " 


Note: If the string is longer than the specified number of 
spaces, the string will be truncated and an ellipsis character 
(...) will be added at the end. 


Related Command: TRIM 
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SUBNUM 


Returns the character code of the nth character of a string. 


SUBNUM 


"string’ n — code 


The commands PUTCHR and SUBNUM are designed for 
applications requiring an index array for values less than 255. 
Using a string to store the indices as character codes saves 
considerable memory compared to other storage methods, 
such as lists or arrays. 


Example: 


"ALPHABET" 4 — #F 


hh 


Related Commands: PUTCHR, STRCON 
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SXCH 


Exchanges objects at levels m and n on the stack. 





« Obj, ... ODjy  --- 


Example: 


53 22 87 341442 —4 58 34 87 22 14 


Related Commands: KEEP, MREVERSE, NDUP, QSORT, 
SRLL, SRLLD 
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TIO 


Converts a string to its translated form for output, respecting 
the current TRANSIO setting in JOPAR. If there is no JOPAR in 
the HOME directory, a new one will be created in the HOME 
directory with the default TRANSIO setting of 1 (see Character 
Translations). 


TIO 


“string,” —> = "string." 


Example: 
"e ¢# x « x SIN x + % #" 


UN<€ Nop rp ONS x SIH xX 4 NOR NED" 


Related Command: TIO— 
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TIO— 


Converts a string from its translated form for output, 
respecting the current TRANSIO setting in JOPAR. If there is 
no JOPAR in the HOME directory, a new one will be created in 
the HOME directory with the default TRANSIO setting of 1 (see 
Character Translations). 


TIO— 


“string,” — — "strings" 


Example: 
"NEE Nob NK x SIN X 7 NOR NDOT 


"¢ ¢ x « « SIH x 7 &» #" 


Related Command: —TIO 
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TRIM 


Removes leading and trailing space and tab (#09h) characters 
from a string. 


TRIM 
“string,” — “string,” 
Example: 
"SAMPLE STRING “ —- "SAMPLE STRIWG" 


Related Commands: LTRIM, RTRIM, STRCTR, ~WORDS 
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UCASE 


Converts each character in a string to uppercase. 


UCASE 


“string,” — = “string,” 


The case conversion supports the ISO 8859-1 character set 
in the following ranges: 


Lowercase Uppercase 


61h-7Ah —- 41h-5Ah 


EOh-F6éh — COh-D6h 
F8h-FEh — D8h-DEh 





Example: 


"sample sentence" —- "SAMPLE SENTENCE" 


Related Commands: ICAPS, LCASE 
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UNION 


Returns the set union of two lists. 


UNION 
{list,} {list,}} — — {lista opp} 


Examples: 
€12343¢£563 4+- €123456 3 


fClesa4¢3(3453 > (12345 3 


Related Commands: ADJOIN, DIFF, INTERSECT, SDIFF, 
—SET 
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VFIND 


Given an global variable name or an object type, VFIND 
performs a recursive search for a global variables starting at 
HOME and returns a series of paths (each of which is a list) to 
each occurrence of a variable in user memory meeting the 


search criteria (see Object Types). 


name — {path,} ... {path,,} n 


type — {path,} ... {path,,} n 





Examples: 


4 3 @ 


8 —-+ ‘¢¢ HOME * 3 £ HOME REALS ‘ 


'A'  — € HOME % 3 © HOME REALS * 3 
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—WORDS 


Separates a string into words and their count. The separation 
characters are any character code <30, 32, and 160. Adjacent 
separator characters are treated as a single separator 
character. 





Examples: 


— 6 


"A TEST STRING" -— "A" "TEST" "STRING" 3 


Related Commands: LTRIM, RTRIM, TRIM 
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XTIME 


Times the execution time for an object such as a command or 
program. An initial garbage collection is performed (see 
Temporary Memory) to produce the most reliable result, and 
the result is rounded to the nearest thousandth of a second. 


XTIME 


object -—+ seconds 


Example: 


* 1 166 START NEXT ® — Time? .387_s 
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Object Types 
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Real number 
Complex number 
String 

Real array 
Complex array 
List 

Global name 
Local name 
Program 
Algebraic 

Binary integer 
Graphics object 
Tagged object 
Unit object 

XLIB name 
Directory 
Library 

Backup object 
Built-in function 
Built — in command 
Library Data 


1.2345 
€2.3,4.53 

"ABC" 

Ci23 ] 

C 1,2) ¢€3;4) J] 
{ "ABC" Var 3 


He2+ & 
uayagt 
# 247d 
Graphic 131 x 64 
Dist: 34.45 
S2_ft/“s*2 
“LIB 766 1 
DIR ... END 
Library 766: ... 
Backup HOMEDIR 
SIH 
SWAP 
Library Data 
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Character Translations 


When data is transferred between the HP 48 and a computer 
using translate codes 2 (000-159) or 3 (000-255), conversions 
are used to represent some characters. The command TRANSIO 
may be used to assert the current translation code. 


For data being transferred to a computer with translate codes 2 or 
3, each ~. is replaced with ~.~.. For data being transferred to the 
HP 48, characters may be converted using a text conversion or 
0x, where 20m is the three-digit (decimal) character code. 


NUM HP 48 ASCII 


é 
v 
I 
t 
> 
T 


+e tf + 2 HH I IK & 


= 


tre 
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Flags 


User flags are numbered 1 through 64. System flags are 
numbered from -1 through —64. By convention, application 
developers are encouraged to restrict their use of user flags to 
the range 31-64. 


All flags are clear by default, except for the wordsize (flags -5 — 
-10). 


Flag Description Clear Set Default 


Symbolic Math Flags 


Principal Solution General solutions | Principal solutions 
Symbolic Constants Symbolic form Numeric form 
Numeric Results Symbolic results Numeric results 


Binary Integer Math Flags 


-5-—+ | Binary integer wordsize n+1:0<n<63 
-10 | Flag -10 is the most significant bit 


Binary Integer Base 


-13 and - 14 are not used. 
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a 


Rectangular Clear Clear 
Cylindrical Polar Clear Set 
Spherical Polar Set Set 


Degrees 
Radians 
Grads 


Vector /complex Vector Complex 


Underflow Exception Return 0, Error 
set -23 or -24 


Overflow Exception Return +MAXR, Error 
set -25 
Infinite Result Error Return +MAXR, 
set -26 

Pos. Underflow Ind. No Exception Exception 
Neg. Underflow Ind. No Exception Exception 
Overflow Indicator No Exception Exception 
Infinite Result Ind. No Exception Exception 


Function Plotting y and f(x) 
Curve Filling Filling Disabled 
Graphics Cursor 
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Flag Description Default 


1/0 and Printing Flags 


1/0 Device Serial 

Printing Device IR Serial 

1/O Data Format ASCII Binary 

RECV Overwrite New variable Overwrite 

Double —- Spaced Print Single Double 
Inserts LF Suppresses LF 


Time Management Flags 


-40 |Clock Display TIME menu only All times TIME menu 
12 hour 24 hour 12 hour 

-42 |Date Format MM/DD/YY DD.MM.YY MM/DD/YY 

-43 |Rpt. Alarm Reschedule 

-44 |Acknowledged Alarms Deleted Saved Deleted 


Notes: If flag —43 is set, unacknowledged repeat alarms are not rescheduled. 
If flag —44 is set, acknowledged alarms are saved in the alarm catalog. 


Display Format Flags 


-45 —|Set the number of digits in Fix, Scientific, and 
-48 |Engineering Modes 
Number 
Display Format 
-49 Clear Clear 
and ie Clear Set 
50 Set Clear 
Set Set 


Fraction Mark Decimal Comma 
Single Line Display Multi-line Single -line Multi-line 
Precedence () suppressed () displayed | Suppressed 
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Miscellaneous Flags 


Not used. 

Last Arguments 

Beep 

Alarm Beep 

Verbose Messages 

Fast Catalog Display 

Alpha Key Action Twice to lock Once to lock Twice 
USR Key Action Twice to lock Once to lock Twice 
User Mode Not active Active Not active 
Vectored Enter Off On Off 





Set by GETI or PUTI when their element indices wrap around 


The HP 82211A HP Solve Equation Library application card uses 
three user flags: 


Units Type SI units English units SI! units 


Units Usage Units used Units not used Units used 
Payment Mode End mode Begin mode End mode 
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Alpha Keyboard 
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The HP 48 Programmer's ToolKit 





Includes Disk for IBM-Compatible Computers 


The HP 48 Programmer's ToolKit is a collection of software tools designed with the 
programmer in mind. These tools improve program performance by combining 
some common, slow operations into faster internal system languages and provide 
additional capability in object manipulation not directly available in the HP 48. 


e The Character Set Catalog is an interactive catalog that displays the HP 48 
character set in all three available fonts and shows the I/O translation forms. 


e The Menu Label Builder is an interactive program for building graphics objects 
for use in custom menus. 


e The Flag Catalog is an interactive program that shows the states and 
descriptions of system and user flags. 


e The Data Browser and Title Browser are two powerful screen-oriented user 
interface utilities that may be used to enhance an application: 


en wat LIS ( Choose a planet: 
5 | VENUS | EART 
123 5 BNYSTREET Frans | SaTuEN—[AUPITER — 
ieaNus—| NEPTUNE | — PLUTO — 












Pp: 97330 
503-555-1212 
iC Bowe oe em 





LSUN [MOON| TEMP] 1ST |OREIT 


e The Tool Library provides 74 new commands for arrays, graphics, list utilities, 
meta-objects, sorting, sets, stack utilities, string utilities, and more. These 
commands are fast and powerful. For instance, the command MREVERSE will 
reverse the order of 1000 objects on the stack in less than a second, and 
ROTATE will rotate character strings, lists, or graphics objects. 


The 124 page manual provides complete descriptions of all the new catalogs, 
programs, and commands with examples. Additional chapters provide reference 
tables for object types, the character set, and flags. 
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